ATOM Documentation

Smart Home Troubleshooting Guide

Common Issues

Device Not Discovered

**Symptoms:**

• Device exists in hub app but not in ATOM SaaS
• Discovery returns 0 devices

**Causes:**

1. Device not paired with hub
2. Hub not connected to network
3. Device excluded from selected location/room
4. Hub firmware outdated

**Solutions:**

1. **Verify hub connectivity:** Check hub app can see devices
2. **Refresh discovery:** Integrations → [Platform] → Discover Devices
3. **Check device pairing:** Pair device with hub first
4. **Restart hub:** Unplug for 30 seconds, plug back in
5. **Update firmware:** Check for hub updates in hub app
6. **Re-pair device:** Remove from hub, re-add, re-discover

**Advanced:**

• Check network: Hub and ATOM SaaS on same network (for local hubs)
• Firewall rules: Allow mDNS (Hue), WebSocket (Home Assistant)
• API limits: Rate limiting may block discovery, wait and retry

---

OAuth Connection Failed

**Symptoms:**

• Authorization page shows error
• Redirect fails with 400/401 error
• Tokens invalid immediately after authorization

**Causes:**

1. Redirect URI mismatch
2. Invalid Client ID or Secret
3. OAuth consent screen not configured
4. Token expired

**Solutions:**

1. **Verify redirect URI:** Must match exactly in OAuth app settings
2. **Check credentials:** Copy-paste Client ID/Secret, ensure no extra spaces
3. **Configure consent screen:** OAuth app must have consent screen configured
4. **Re-authorize:** Revoke old tokens, run OAuth flow again
5. **Check app status:** Verify OAuth app is active in developer console

**Platform-specific:**

• **SmartThings:** Check API Key permissions, ensure scope includes r:devices:*
• **Nest:** Verify Google Cloud project has SDM API enabled
• **Alexa:** Check security profile credentials, redirect URL in LWA console

---

Device Not Responding

**Symptoms:**

• Command sent but device doesn't change state
• State shows "offline" or "unreachable"
• Commands timeout

**Causes:**

1. Device powered off or disconnected
2. Device out of range of hub
3. Hub offline or disconnected from network
4. Rate limiting (commands delayed)
5. Device firmware bug

**Solutions:**

1. **Check device power:** Verify device is plugged in, battery charged
2. **Check hub status:** Hub app shows hub online?
3. **Test in hub app:** Control device from hub app (rules out hub/device issue)
4. **Sync device state:** ATOM SaaS → Devices → [Device] → Sync
5. **Check distance:** Device within range of hub? (Zigbee/Z-Wave ~100ft)
6. **Restart device:** Unplug for 30 seconds, plug back in
7. **Re-pair device:** Remove from hub, re-add
8. **Check for interference:** Microwaves, other wireless devices

**Rate limiting:**

• Hue: 10 req/sec limit, commands auto-queued
• SmartThings: 150 req/min, exponential backoff on 429
• Nest: 1500 req/min, rarely hit limit

---

State Not Syncing

**Symptoms:**

• Device state in ATOM SaaS doesn't match actual state
• State updates delayed by minutes/hours
• State shows "unknown" or "error"

**Causes:**

1. Polling interval too long
2. WebSocket disconnected (Home Assistant)
3. Hub not reporting state changes
4. State cache outdated

**Solutions:**

1. **Manually sync:** Devices → [Device] → Sync
2. **Adjust polling:** Integrations → [Platform] → Poll Interval (reduce for faster updates)
3. **Check WebSocket:** Home Assistant → WebSocket Status (should be "Connected")
4. **Verify hub reporting:** Check hub app for state changes, hub push notifications enabled
5. **Clear cache:** Devices → [Device] → Clear Cache → Sync
6. **Restart integration:** Integrations → [Platform] → Restart

**WebSocket issues (Home Assistant):**

• Check HA logs for WebSocket errors
• Verify long-lived access token is valid
• Test WebSocket connection: Browser DevTools → WS → connect to ws://ha-url/api/websocket
• Reconnect: Integrations → Home Assistant → Reconnect

---

Rate Limit Errors

**Symptoms:**

• API returns 429 status code
• Commands delayed or queued
• "Rate limit exceeded" error messages

**Causes:**

1. Too many API calls in short time
2. Polling interval too short
3. Too many automations triggering at once
4. Bulk operations on many devices

**Solutions:**

1. **Reduce polling frequency:** Increase poll interval (default: 5-10 seconds)
2. **Use webhooks:** Enable webhooks for real-time updates instead of polling
3. **Batch commands:** Use scenes/groups instead of individual device control
4. **Add delays in automations:** Spread out device control over time
5. **Optimize automations:** Reduce number of automations, combine where possible
6. **Check usage:** Integrations → [Platform] → Rate Limits (view current usage)

**Platform limits:**

• Hue: 10 req/sec (strict, enforced by bridge)
• SmartThings: 150 req/min (enforced by cloud API)
• Nest: 1500 req/min (generous, rarely hit)
• Home Assistant: Unlimited (local WebSocket)

---

Hub-Specific Issues

Hue Bridge Not Found

**Diagnosis:**

• Hue app can find bridge? → Yes: Bridge OK, ATOM SaaS network issue
• Hue app can't find bridge? → No: Bridge network issue

**Solutions:**

1. **Check bridge LEDs:** 3 blue LEDs = network OK, 1 blinking = searching for network
2. **Manual IP entry:** Discover → Manual Entry → Enter bridge IP (find in Hue app → Settings → My Bridge → Network info)
3. **Network check:** Bridge and ATOM SaaS on same network? Same subnet?
4. **Firewall:** Allow mDNS (UDP port 5353), TCP port 80
5. **Restart bridge:** Unplug 30 seconds, plug back in
6. **Factory reset:** Last resort (hold button until LED flashes)

**mDNS issues:**

• macOS: System Preferences → Security → Firewall → Allow incoming connections
• Windows: Windows Firewall → Allow mDNS
• Router: Enable mDNS/Bonjour/UPnP

---

SmartThings API Errors

**Error Codes:**

• 400: Invalid request, bad parameters
• 401: Unauthorized, tokens expired
• 403: Forbidden, insufficient permissions
• 404: Device/location not found
• 429: Rate limit exceeded
• 500: SmartThings cloud error

**Solutions:**

1. **Check tokens:** Integrations → SmartThings → Re-authenticate
2. **Verify scope:** OAuth app must have r:devices:* and x:devices:*
3. **Check location:** Device exists in selected location?
4. **Review permissions:** OAuth app has permission for device type?
5. **SmartThings status:** Check status.smartthings.com
6. **Reduce polling:** Increase poll interval to avoid rate limits

**Device not in SmartThings:**

• Device must be paired with SmartThings Hub first
• Check SmartThings app → My Home → Devices
• Exclude/include device: SmartThings app → Device → Remove, re-add

---

Home Assistant Connection Issues

**WebSocket Connection Failed:**

**Diagnosis:**

1. Test in browser: ws://your-ha-url:8123/api/websocket
2. Check HA logs: Settings → System → Logs → WebSocket errors
3. Verify token: Profile → Long-Lived Access Tokens → Regenerate

**Solutions:**

1. **Regenerate token:** Old token may have expired
2. **Check URL:** Include port (default: 8123), use ws:// or wss:// for HTTPS
3. **CORS settings:** configuration.yaml must include ATOM SaaS domain:

• https://your-atom-saas-domain.com

1. **Restart HA:** Configuration → Server Controls → Restart
2. **Check firewall:** Allow TCP port 8123
3. **Use HTTPS:** For remote HA, enable SSL, use wss://

**Entity Not Found:**

• Check entity ID in HA (Developer Tools → States)
• Entity must be enabled (disable/enable in HA)
• ATOM SaaS filters hidden entities by default

---

Nest Authentication Failures

**OAuth Flow Errors:**

**Common errors:**

• redirect_uri_mismatch: Redirect URI doesn't match OAuth app
• access_denied: User denied authorization
• invalid_client: Client ID/Secret wrong
• unauthorized_client: OAuth app misconfigured

**Solutions:**

1. **Verify redirect URI:** Exactly match in Google Cloud Console
2. **Check OAuth screen:** Consent screen configured, published
3. **Verify scopes:** https://www.googleapis.com/auth/sdm.service enabled
4. **Check billing:** Google Cloud project must have billing enabled (even for free tier)
5. **Test OAuth:** Use OAuth 2.0 Playground
6. **Recreate credentials:** Delete OAuth client, create new

**No Devices Found:**

• Device must be in Google Home app
• Check structure: OAuth linked to correct home/structure?
• Device type: Only thermostats supported currently (SDM API limitation)
• Firmware: Nest device must be updated to latest firmware

---

Automation Issues

Rule Not Triggering

**Diagnosis:**

1. Check run history: Automations → [Automation] → Run History
2. View current states: Compare trigger conditions with actual device states
3. Test manually: Automations → [Automation] → Test Run

**Solutions:**

1. **Verify trigger conditions:** Are trigger conditions actually met?
2. **Check device states:** View device state, compare with trigger
3. **Verify time zone:** Automation time zone matches your location?
4. **Check enablement:** Automation is enabled (not disabled)?
5. **Review conditions:** All conditions must be true (AND) or any true (OR)
6. **Circular dependency:** Rule triggers itself? (causes infinite loop)

**Example:**

• Trigger: "Motion detected"
• Check: Motion sensor shows "active" in device state?
• If not: Motion sensor not working, not trigger issue

---

Conditions Not Evaluating

**Symptoms:**

• Conditions always false
• Conditions never met
• Logic not working as expected

**Solutions:**

1. **Test conditions individually:** Create automation with single condition, test
2. **Check logical operators:** AND = all true, OR = any true, NOT = inverted
3. **Verify comparison:** > vs >=, = vs contains
4. **Check time zones:** Time range in local time zone?
5. **Review condition order:** Conditions evaluated top-to-bottom
6. **Test rule manually:** Automations → [Automation] → Test

**Complex conditions:**

• Break into multiple rules (simpler debugging)
• Use scenes instead of complex logic
• Add logging action (send notification) to see execution flow

---

Actions Failing

**Symptoms:**

• Automation triggers but actions don't execute
• Partial execution (some actions work, some fail)
• Actions timeout

**Solutions:**

1. **Test actions individually:** Device control page → Execute action
2. **Check device connectivity:** Device online? Hub online?
3. **Verify capability:** Device supports the action? (e.g., basic bulb can't change color)
4. **Check rate limits:** Too many actions in short time?
5. **Review action parameters:** Correct format? (brightness 0-254 for Hue, 0-100 for SmartThings)
6. **Add delays:** Spread out actions over time (avoid rate limits)

**Partial execution:**

• Actions executed sequentially, first failure stops execution
• Enable "Continue on error" in automation settings
• Use error handling per action (retry, fallback, skip)

---

Schedule Not Running

**Symptoms:**

• Scheduled automation doesn't run at specified time
• Runs at wrong time
• Runs multiple times

**Solutions:**

1. **Check cron expression:** Verify format, test in crontab guru
2. **Verify time zone:** Schedule in correct time zone?
3. **Check enablement:** Automation enabled?
4. **Review history:** Automations → [Automation] → Run History (last run time)
5. **Server time:** ATOM SaaS server time correct?
6. **Sunset/sunrise:** Location set correctly? (affects sunrise/sunset times)

**Time zone issues:**

• Automation uses tenant time zone (Settings → Tenant → Time Zone)
• Schedules stored in UTC, displayed in local time
• Daylight saving time: Automatic if time zone set correctly

---

Diagnostic Tools

Connection Testing

Test connectivity to hubs:

1. **Navigate:** Integrations → [Platform] → Test Connection
2. **View results:**

• ✓ Online: Hub reachable
• ✗ Offline: Hub not reachable
• ⚠ Latency: Connection slow (>500ms)

1. **Interpret results:**

• Online but high latency: Network congestion, distance
• Offline: Check hub power, network, firewall

State Viewing

View raw device state for debugging:

1. **Navigate:** Devices → [Device] → View State
2. **See:**

• Current state (on/off, brightness, etc.)
• Last updated timestamp
• State source (hub, cached, manual)

1. **Compare:** Check against hub app state
2. **Sync:** If stale, click "Sync" to refresh

Log Analysis

View integration logs:

1. **Navigate:** Settings → Logs → Smart Home
2. **Filter by:**

• Platform (Hue, SmartThings, etc.)
• Device ID
• Date range
• Log level (Error, Warning, Info, Debug)

1. **Export:** Download logs for support ticket
2. **Common log entries:**

• Rate limit exceeded: Too many API calls
• Device offline: Hub reports device unreachable
• Auth failed: Token expired, re-authenticate
• Connection timeout: Network issue

Rate Limit Monitoring

Monitor API usage:

1. **Navigate:** Integrations → [Platform] → Rate Limits
2. **View:**

• Current usage: Requests in last minute
• Limit: Max requests per period
• % Used: Usage as percentage of limit

1. **Timestamps:** See request times to identify spikes
2. **Optimize:** If consistently near limit, reduce polling

---

Recovery Procedures

Re-authentication

If OAuth tokens expire:

1. **Navigate:** Integrations → [Platform] → Settings
2. **Click:** "Re-authenticate"
3. **Complete OAuth flow:** Authorize again
4. **Verify:** Devices re-discovered, tokens valid

**Prevent token expiry:**

• Tokens auto-refresh before expiry (SmartThings, Nest)
• Long-lived tokens don't expire (Home Assistant)
• Re-authenticate annually for security

Device Rediscovery

Refresh device list:

1. **Navigate:** Integrations → [Platform] → Discover Devices
2. **Process:**

• Existing devices: Updated (name, capabilities, state)
• New devices: Added to device registry
• Removed devices: Marked offline (not deleted)

1. **Review:** Check device list for accuracy
2. **Clean up:** Delete old/removed devices

Factory Reset Integration

**Warning:** Removes all devices, automations, scenes

**When to use:**

• Integration completely broken
• OAuth cannot be fixed
• Major hub firmware update

**Steps:**

1. **Navigate:** Integrations → [Platform] → Settings
2. **Scroll:** Bottom of page
3. **Click:** "Reset Integration"
4. **Confirm:** Enter integration name to confirm
5. **Wait:** Integration removed, data cleared
6. **Re-setup:** Follow initial setup process

**Before factory reset:**

• Export automations and scenes (if available)
• Note device configurations (names, rooms)
• Save OAuth credentials (may still work)

---

Getting Help

Self-Service Resources

• **Integration Guide:** INTEGRATION_GUIDE.md
• **Automation Guide:** AUTOMATION_GUIDE.md
• **Voice Control:** VOICE_CONTROL.md
• **Community Forum:** Post questions, search similar issues

Support Contact

For platform issues or bugs:

• **Email:** support@atom-saas.com
• **Include:**
• Platform (Hue, SmartThings, etc.)
• Error messages (screenshots helpful)
• Steps to reproduce
• Diagnostic logs (export from Settings → Logs)
• Browser console errors (if web UI issue)

Response Times

• **Critical issues:** All hubs down, security vulnerabilities (4 hours)
• **High priority:** Automation failures, major features broken (24 hours)
• **Normal priority:** Minor bugs, documentation questions (48 hours)
• **Low priority:** Feature requests, improvements (1 week)